Project Management

As the amount of documents you are processing grows, so does the amount of work required to maintain the whole bunch of your (wannabe-)information. To reduce waste of time for stupid project management tasks, hsc is able to maintain a project file and to utilize some additional tools.

Overview

As there are several tools and concepts involved in project management. Within the next paragraphs, the basic ideas will be roughly described. If you already worked with a command line based compiler environment and know how Makefiles and a dependency creator work, there should not be many new things.

If you did not, there is quite some work in front of you. For details about the aforementioned things, you can refer to the chapters listed below, but this is not meant to be an idiot-proof tutorial to make.

Project Files - where hsc stores the required information.
hscpitt - hsc's project interfering and trashing tool
make - a general purpose tool for project management
Makefiles - how to adept them for hsc
hscdepp - hsc's dependency procreator
hscpaltrow - utilizing the output of hscpitt.

Creating A New Project

The first step is to create a project-file. This simply can be done by

hscpitt new

This will create an empty project in the current directory with no documents in it. To see which documents are part of your project, you can use

hscpitt list

or, if you do not want to see the header displayed:

hscpitt quiet list

All these commands will use a default name, ``hsc.project'' for the project-file. If you want to use a different name, you can use the CLI-option PRJFILE, for example:

hscpitt prjfile=sepp.project new

But note that then you will have to specify this option every time you invoke hscpitt or hscdepp.

Adding New Documents To The Project

There are two ways to add a document to the project: the first is hsc, because is will automatically add or update document entries in the project-file after it successfully wrote a document to the storage.

To make hsc keep the project-file up-to-date, you have to use the CLI-option PRJFILE=projec_file. For example,you can invoke hsc using

hsc FROM=sepp.hsc TO=html:sepp-pages/ PRJFILE=hsc.project

Maintaining The Makefile

Another possibility is for adding documents is hscpitt. For example:

hscpitt add html:sepp-pages/sepp.html sepp.hsc

will add the same document and main source file as before to the project. This can be handy if you have a big and fat pattern rule with many options that will take care of invoking hsc after a new dependency has been added to the Makefile. This relieves you from typing in a long sequence of command line options.

Nevertheless hscpitt leaves the Makefile untouched. Actually you do not need a Makefile at all to use hscpitt - it only stores information in project-file.

So if you invoke make right after hscpitt, nothing will have changed. To translate the contents of the project-file into a list of dependencies, you will have to use hscdepp. This tool simply creates a dependency line for every document it finds in the project-file, and stores this information in a Makefile.

For example, after the call to hscpitt done before, hscdepp will create the dependency

html:sepp-pages/sepp.html : sepp.hsc

Or, if you would have used relative paths on a NeXTStep system like

hscpitt add ../../sepp-pages/sepp.html sepp.hsc

the dependency would look like:

../../sepp-pages/sepp.html : sepp.hsc

However, hscdepp does not care about the rules and options for hsc you use in the Makefile. It only takes care of the dependencies, and everything else is up to you.

When To Call Hscdepp

As all hsc and hscpitt are completely independent from make, and hscdepp only provides an optional link between them. In other words: hsc does not care if it is invoked from a Makefile or not. And make does not care about the project-file, but only about its own Makefile.

Therefor every time something changed in the project-file, it is left to the user to invoke hscdepp and also reflect these changes in the Makefile.

In general, it is a good idea to call hscdepp after..

adding a new document document using hscpitt or hsc
successfully processing new a document with hsc the first time after adding it with hscpitt, because then it not only depends on its main source, but also on the files included during processing.
changing the include files of your pattern rule in the Makefile
once in a while.

Of course sometimes it can be convenient not to call hscdepp, for example when you add multiple documents by calling hscpitt several times, without invoking hsc or make meanwhile. Nevertheless, invoking hscdepp too often should not cause any harm.

Checking IDs

The usage of the project-file also improves the functionality of hsc. It will now also remember which IDs for link targets inside a document have been defined (for example using html-code like <A NAME="id">).

Now hsc will not only whine about code like

<A HREF="#unknown">

but also

<A HREF="existing.html#unknown">

with in both cases the ID ``unknown'' not being defined within the document, but the document existing.html being in place.

Until all documents have been added to the project (either by hsc or hscpitt), message #51 ("no entry for document .. to check id") might show up some times. This can be ignored.

Until all documents have been processed by hsc with a PRJFILE set at least once (not only been added by hscpitt) to the project-file), there will also be some occurrences of message #74 ("unknown id") you can ignore. This is because even if the IDs are actually defined in the document, hsc does not yet know about them because it did not store them in the project-file, too.

Alternative Approaches

It should be emphasized that all of the above tools and concepts are optional to hsc. You do not have to use hscdepp to maintain your dependencies, but can also do manually, without any pattern rules in the Makefile.

You even do not have to use make, but a different tool for project management. Although then you will have too find a substitute for hscdepp, if you still want to maintain the dependencies automatically. Maybe hscpaltrow can help you with this.

Of course you can use hsc without a project-file at all, and for example use a simple Shell- or Rexx-script to convert all your documents, if there are only few of them.

Example Projects

There are some example project included, with most of them consisting of only a few sample documents. To try them out, open a Shell and change into the corresponding directory with the Makefile. View the README if there are some preparations needed.

Maybe you will also have to change the variables HSC to point to the hsc-executable and DESTDIR to contain the name of the parent directory, which differs from system to system. Use ``/'' for AmigaOS or ``../'' for most other systems.

Fetzenschädl: This project is located in examples/fetzenschaedl/. There you will also find a README and a Makefile. Both html-document and hsc-source will be located in the same directory, which makes maintenence easier, but has several obstacles shortly discussed there. It uses a Makefile, but no project-file, so only hsc and make are required to try is out.
Simple: This project is located in examples/simple/. There you will also find a README and a Makefile. These are the same documents as before, but now html-objects will be located in a different directory you will have to create manually. Only a few changes to the Makefile are required to accomplish this.
Advanced: This project is located in docs/source/ and contains the source code used to create this manual. See docs-source/README. The Makefile used for this utilizes hscdepp and contains a pattern rule to also validate the created document with an external html-checker.